Documentation
¶
Overview ¶
Package trust implements the registry's trust-pair and handshake-relay store. It is extracted from pkg/registry/server as part of the R2.1 registry decomposition.
Thread safety: all exported methods are safe for concurrent use.
Index ¶
- type Callbacks
- type HandshakeRelayMsg
- type HandshakeResponseMsg
- type NodeView
- type Store
- func (st *Store) Count() int
- func (st *Store) HandleCheckTrust(req map[string]interface{}) (map[string]interface{}, error)
- func (st *Store) HandlePollHandshakes(req map[string]interface{}) (map[string]interface{}, error)
- func (st *Store) HandleReportTrust(req map[string]interface{}) (map[string]interface{}, error)
- func (st *Store) HandleRequestHandshake(req map[string]interface{}) (map[string]interface{}, error)
- func (st *Store) HandleRespondHandshake(req map[string]interface{}) (map[string]interface{}, error)
- func (st *Store) HandleRevokeTrust(req map[string]interface{}) (map[string]interface{}, error)
- func (st *Store) InboxSize() (requests, responses int)
- func (st *Store) InboxSnapshot() (inbox map[uint32][]*HandshakeRelayMsg, ...)
- func (st *Store) IsTrusted(a, b uint32) bool
- func (st *Store) Pairs() []string
- func (st *Store) RestoreInbox(inbox map[uint32][]*HandshakeRelayMsg, ...)
- func (st *Store) RestorePairs(keys []string)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Callbacks ¶
type Callbacks struct {
// Save triggers a debounced snapshot write.
Save func()
// Audit records an audit log entry.
Audit func(action string, attrs ...any)
// IncTrustReports increments the trust-reports counter.
IncTrustReports func()
// IncTrustRevocations increments the trust-revocations counter.
IncTrustRevocations func()
// IncHandshakeRequests increments the handshake-requests counter.
IncHandshakeRequests func()
}
Callbacks bundles the side-effect functions the Store calls on state changes. All functions must be safe for concurrent use.
type HandshakeRelayMsg ¶
type HandshakeRelayMsg struct {
FromNodeID uint32 `json:"from_node_id"`
Justification string `json:"justification"`
Timestamp time.Time `json:"timestamp"`
}
HandshakeRelayMsg is a handshake request stored in the registry's relay inbox.
type HandshakeResponseMsg ¶
type HandshakeResponseMsg struct {
FromNodeID uint32 `json:"from_node_id"` // the node that approved/rejected
Accept bool `json:"accept"`
Timestamp time.Time `json:"timestamp"`
}
HandshakeResponseMsg is a handshake approval/rejection stored for the original requester.
type NodeView ¶
type NodeView interface {
// LookupNode returns the public key and network memberships for the
// given node ID. ok is false when the node does not exist.
LookupNode(id uint32) (pubKey []byte, networks []uint16, ok bool)
// AdminToken returns the global admin token for the registry.
// An empty string means administration is disabled.
AdminToken() string
}
NodeView is the read-only interface the Store uses to look up node data. Implementations must be safe for concurrent use.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds all mutable trust-pair and handshake-relay state.
LOCK ORDERING
mu (RWMutex) — protects trustPairs.
handshakeMu (Mutex) — protects handshakeInbox, handshakeResponses,
and pendingHandshakes.
These two locks are independent; neither may be acquired while holding the other. No code path needs both simultaneously.
func (*Store) HandleCheckTrust ¶
HandleCheckTrust reports whether a trust pair exists between two nodes, or whether they share a non-backbone network.
func (*Store) HandlePollHandshakes ¶
HandlePollHandshakes returns and clears a node's handshake inbox.
Uses the 3-phase pattern: look up node + copy pubkey, release, verify signature without any lock (CPU-bound ~28µs), then swap inbox maps.
func (*Store) HandleReportTrust ¶
HandleReportTrust registers a mutual trust pair between two nodes.
func (s *Server) handleReportTrust(req map[string]interface{}) (map[string]interface{}, error) {
return s.trust.HandleReportTrust(req)
}
func (*Store) HandleRequestHandshake ¶
HandleRequestHandshake relays a handshake request to a target node's inbox. M12 fix: verifies sender signature to prevent spoofed handshake requests.
func (*Store) HandleRespondHandshake ¶
HandleRespondHandshake processes a handshake response (approve/reject). If approved, creates a mutual trust pair. M12 fix: verifies responder signature to prevent spoofed trust approvals.
3-phase pattern: look up pubkey, verify signature without lock, then write trust pair + response inbox.
func (*Store) HandleRevokeTrust ¶
HandleRevokeTrust removes a trust pair between two nodes.
func (*Store) InboxSize ¶
InboxSize returns the total number of pending handshake requests and responses (for metrics gauges).
func (*Store) InboxSnapshot ¶
func (st *Store) InboxSnapshot() ( inbox map[uint32][]*HandshakeRelayMsg, responses map[uint32][]*HandshakeResponseMsg, )
InboxSnapshot returns copies of the handshake inboxes for snapshot serialisation. Called during snapshot flush.
func (*Store) IsTrusted ¶
IsTrusted reports whether nodes a and b have an established trust pair. The relation is symmetric: IsTrusted(a, b) == IsTrusted(b, a).
func (*Store) Pairs ¶
Pairs returns a snapshot of all trust-pair keys for serialisation. Each key is of the form "min:max" where min <= max.
func (*Store) RestoreInbox ¶
func (st *Store) RestoreInbox( inbox map[uint32][]*HandshakeRelayMsg, responses map[uint32][]*HandshakeResponseMsg, )
RestoreInbox loads handshake inboxes from a snapshot during startup. NOT safe for concurrent use — call before serving requests.
func (*Store) RestorePairs ¶
RestorePairs loads trust pairs from a snapshot during startup. It is NOT safe for concurrent use — call it before serving requests.
Source Files