macula_realm_trust (macula v0.20.5)

Realm Trust Management for Hybrid Trust Model

Implements the Hybrid Trust Model (ADR-001) with three trust levels: - Level 1: Realm Authentication (API key/token validation) - Level 2: Certificate Trust (TOFU within authenticated realm) - Level 3: Optional CA-signed certificates for seed nodes

This module manages: - Realm authentication via API keys - Certificate fingerprint registration and verification - Trust On First Use (TOFU) pattern - Fingerprint change detection - Trust revocation

Summary

Types

fingerprint/0

node_id/0

realm/0

session/0

Functions

authenticate(Realm, ApiKey)

Authenticate to a realm using API key Returns a session map on success, error tuple on failure Implements rate limiting per realm

extract_fingerprint(CertPEM)

Extract SHA-256 fingerprint from certificate PEM

get_auth_attempt_count(Realm)

Get the current auth attempt count for a realm

get_fingerprint_info(Realm, NodeId)

Get fingerprint info for a node in a realm

get_trusted_peers(Realm)

Get all trusted peers in a realm

init_rate_limiter()

Initialize the rate limiter ETS table

register_fingerprint(Realm, NodeId, Fingerprint)

Register a certificate fingerprint for a node in a realm

reset_rate_limit(Realm)

Reset the rate limit for a realm

revoke_trust(Realm, NodeId)

Revoke trust for a node in a realm

verify_fingerprint(Realm, NodeId, Fingerprint)

Verify a certificate fingerprint for a node in a realm Implements Trust On First Use (TOFU) - first connection is automatically trusted

Types

fingerprint/0

-type fingerprint() :: binary().

node_id/0

-type node_id() :: binary().

realm/0

-type realm() :: binary().

session/0

-type session() :: #{realm := realm(), session_token := binary(), authenticated_at := integer()}.

Functions

authenticate(Realm, ApiKey)

-spec authenticate(realm(), binary()) -> {ok, session()} | {error, term()}.

Authenticate to a realm using API key Returns a session map on success, error tuple on failure Implements rate limiting per realm

extract_fingerprint(CertPEM)

-spec extract_fingerprint(binary()) -> {ok, fingerprint()} | {error, term()}.

Extract SHA-256 fingerprint from certificate PEM

get_auth_attempt_count(Realm)

-spec get_auth_attempt_count(realm()) -> {ok, non_neg_integer()}.

Get the current auth attempt count for a realm

get_fingerprint_info(Realm, NodeId)

-spec get_fingerprint_info(realm(), node_id()) -> {ok, map()} | {error, not_found}.

Get fingerprint info for a node in a realm

get_trusted_peers(Realm)

-spec get_trusted_peers(realm()) -> {ok, [map()]}.

Get all trusted peers in a realm

init_rate_limiter()

-spec init_rate_limiter() -> ok.

Initialize the rate limiter ETS table

register_fingerprint(Realm, NodeId, Fingerprint)

-spec register_fingerprint(realm(), node_id(), fingerprint()) -> {ok, registered}.

Register a certificate fingerprint for a node in a realm

reset_rate_limit(Realm)

-spec reset_rate_limit(realm()) -> ok.

Reset the rate limit for a realm

revoke_trust(Realm, NodeId)

-spec revoke_trust(realm(), node_id()) -> {ok, revoked | not_found}.

Revoke trust for a node in a realm

verify_fingerprint(Realm, NodeId, Fingerprint)

-spec verify_fingerprint(realm(), node_id(), fingerprint()) ->
                            {ok, trusted | trusted_first_use} |
                            {error,
                             {fingerprint_mismatch,
                              #{expected := fingerprint(), received := fingerprint()}}}.

Verify a certificate fingerprint for a node in a realm Implements Trust On First Use (TOFU) - first connection is automatically trusted