macula_hyparview_endorsement (macula v10.22.0)

View Source

Realm-join handshake helpers (Phase 5.6).

Building block for the admission flow of a new station into a realm. The station presents a signed realm_member_endorsement record (issued by the realm admin) and the receiving peers verify it against the realm's admin key before admitting the station into the HyParView active/passive view.

This module is pure — it does not talk to the network. Callers (typically the per-station dispatcher) feed the decoded endorsement record into verify_endorsement/3 and act on the outcome.

Acceptance rules

  • Record type MUST be the endorsement tag (#?TYPE_REALM_MEMBER_ENDORSEMENT).
  • Envelope signature MUST verify against the admin key the local node trusts for that realm. verify/1 guards both signature and expiry already.
  • Payload realm field MUST equal the expected realm id.
  • Payload member_node field MUST equal the candidate node id claimed by the joining peer — prevents stealing another member's endorsement.
  • valid_from ≤ now ≤ valid_until — the endorsement must be currently active.

Reference: plans/PLAN_MACULA_V2_PART6_PROTOCOL.md §9.6.

Summary

Types

node_id/0
realm/0
verify_error/0

Functions

build_join(Realm, NewMember, Endorsement, Identity)

Build the initial JOIN frame the joining station sends to one of the realm's known stations.

verify_endorsement(Record, Realm, Member)

Verify an endorsement record authorises Member for Realm.

Types

node_id/0

-type node_id() :: <<_:256>>.

realm/0

-type realm() :: <<_:256>>.

verify_error/0

-type verify_error() ::
          bad_record | signature_invalid | expired | wrong_type | wrong_realm | wrong_member |
          not_yet_valid | endorsement_expired.

Functions

build_join(Realm, NewMember, Endorsement, Identity)

-spec build_join(realm(), node_id(), macula_record:m_record(), macula_identity:key_pair()) ->
                    macula_frame:frame().

Build the initial JOIN frame the joining station sends to one of the realm's known stations.

The joining station signs the frame with Identity so the receiver can bind the join attempt to the candidate member key (the endorsement binds it to the realm).

verify_endorsement(Record, Realm, Member)

-spec verify_endorsement(macula_record:m_record(), realm(), node_id()) ->
                            {ok, [binary()]} | {error, verify_error()}.

Verify an endorsement record authorises Member for Realm.

Returns {ok, Roles} with the endorsed role list on success, or {error, Reason} otherwise. Callers typically treat any error as a rejection and drop the pending join.